home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / ulog / Ulog.man < prev    next >
Encoding:
Text File  |  1988-12-31  |  5.3 KB  |  136 lines
  1. '\" $Header: /sprite/src/lib/c/ulog/RCS/Ulog.man,v 1.1 88/12/30 16:20:46 ouster Exp $ SPRITE (Berkeley)
  2. .so \*(]ltmac.sprite
  3. .HS Ulog lib
  4. .BS
  5. .SH NAME
  6. Ulog \- obtain or update information in the database of user logins and logouts.
  7. .SH SYNOPSIS
  8. .nf
  9. \fB#include    <ulog.h>\fR
  10.  
  11. Ulog_Data *
  12. \fBUlog_LastLogin\fR(\fIuid\fP)
  13.  
  14. int
  15. \fBUlog_GetAllLogins\fR(\fInumEntries, locPtr, dataArray\fP)
  16.  
  17. int
  18. \fBUlog_RecordLogin\fR(\fIuid, location, portID\fP)
  19.  
  20. int
  21. \fBUlog_RecordLogout\fR(\fIuid, portID\fP)
  22.  
  23. int
  24. \fBUlog_ClearLogins\fR()
  25.  
  26. .SH ARGUMENTS
  27.  
  28. .AS Ulog_Data dataArray[] 
  29. .AP int uid in
  30. A numerical identifier for a user for whom to retrieve or update information.
  31. .AP int numEntries in
  32. The number of Ulog_Data structures contained in \fIdataArray\fP.
  33. .AP int *locPtr in/out
  34. A pointer to an integer specifying the index of the next record in
  35. the user log to access.  
  36. .AP Ulog_Data dataArray[] out
  37. A buffer to hold Ulog_Data entries returned by the Ulog_GetAllLogins routine.
  38. .AP char *location in
  39. String specifying location of user logging in (i.e., remote host)
  40. .AP int portID in
  41. Numerical identifier for login port.
  42. .BE
  43. .SH DESCRIPTION
  44. The ulog library provides a facility to record logins and logouts in
  45. the system, to retrieve information about the last time a user
  46. logged in or about 
  47. all users logged into the system, and to clear the login entries for a
  48. host.  Each host has a fixed number of 
  49. entries allocated to it in the user log
  50. database file.  One entry, with a \fIportID\fP of
  51. \fBULOG_LOC_CONSOLE\fP, is reserved for the console of a host; there
  52. are (\fBULOG_MAX_PORTS\fP - 1) other
  53. entries available for rlogin processes.  (There is currently no
  54. facility for multiple local logins, such as over a serial line.)
  55. .PP
  56. The \fIulog\fP library converts between the ASCII representation stored in the
  57. database and an internal C structure, known as a Ulog_Data structure.
  58. This structure contains information giving <uid,hostID,portID>
  59. corresponding to a user logged in on a particular ``port'' on a
  60. particular host.  Each login entry also includes the time of the
  61. login, which is the \fBtv_sec\fP part of a \fBtime\fP structure.  It
  62. also includes any additional information for the location of the user;
  63. this is an arbitrary string that typically gives the host from which
  64. an rlogin occurs.
  65. Two database files are used: one for logins on a host/port basis, and
  66. one for the last login by each user.
  67. .PP
  68. A Ulog_Data structure is defined as follows:
  69. .DS L
  70. .ta 4n 2.5c 6.5c
  71. \fBtypedef struct\fR {
  72.     \fBint\fP \fIuid\fP;        /* user identifier */
  73.     \fBint\fP \fIhostID\fP;        /* host for which data is
  74.                        valid */
  75.     \fBint\fP \fIportID\fP;        /* port within host */
  76.     \fBint\fP \fIupdated\fP;    /* login time (in seconds since
  77.                        1/1/70); 0 if invalid */
  78.     \fBchar\fP \fIlocation\fP[\fBULOG_LOC_LENGTH\fP];
  79.                     /* location of user */
  80. } Ulog_Data;
  81. .DE
  82. .PP
  83. The \fBUlog_LastLogin()\fR procedure returns a pointer to a
  84. statically-allocated Ulog_Data structure.  Therefore, the contents of the
  85. structure may change on subsequent calls to \fBUlog_LastLogin()\fR.  The
  86. information returned by \fBUlog_LastLogin()\fR corresponds to the most
  87. recent login by the user specified by \fIuid\fP.
  88. .PP
  89. \fBUlog_GetAllLogins()\fR provides a mechanism for retrieving multiple login
  90. entries at once.  The user must allocate an array of Ulog_Data
  91. structures, and pass the size of the array and a pointer to it as
  92. arguments to \fBUlog_GetAllLogins()\fR.  In addition, the \fIlocPtr\fP
  93. argument specifies where in the login database to start looking.
  94. \fI*locPtr\fP 
  95. should be initialized to 0 prior to the first call to
  96. \fBUlog_GetAllLogins()\fR.  \fBUlog_GetAllLogins()\fR returns the number of
  97. entries in \fIdataArray\fP that were filled.  If that number is less
  98. than the maximum number specified by \fInumEntries\fP, then all data
  99. has been returned.  If it is equal to \fInumEntries\fP, then
  100. \fBUlog_GetAllLogins()\fR should be called again to retrieve additional
  101. entries from  the point at which the last call left off (given by
  102. \fI*locPtr\fP). 
  103. .PP
  104. \fBUlog_RecordLogin()\fR allows the caller to register information
  105. for a new login.  The caller specifies the user ID, location, and port
  106. of the user logging in.  The procedure obtains the hostID and current
  107. time, and records the login.
  108. .PP
  109. \fBUlog_RecordLogout()\fR provides a similar facility to record logouts.  It
  110. takes a user ID and port number, and it removes the corresponding
  111. loginn from the list
  112. of active logins.
  113. .PP
  114. \fBUlog_ClearLogins()\fR may be used at boot time to clear any old entries
  115. in the user log for the current host.  Note: if a host is down, it may
  116. still have entries in the user log.  It is the responsibility of the
  117. user to use the migration information database to determine if a host
  118. is up, in order to validate user log entries.
  119. .SH DIAGNOSTICS
  120. \fBUlog_RecordLogin()\fR, \fBUlog_RecordLogout()\fR, and \fBUlog_ClearLogins()\fR return zero if
  121. all went well.  Otherwise 
  122. they return -1 and the \fIerrno\fR variable contains additional information
  123. about what error occurred.  \fBUlog_GetAllLogins()\fR similarly returns -1 on
  124. error, but it returns 0 if no more records are available.  \fBUlog_LastLogin()\fR
  125. returns
  126. NULL on error. 
  127. .SH FILES
  128. .IP /sprite/admin/data/userLog
  129. The database of current logins on each host.
  130. .IP /sprite/admin/data/lastLog
  131. The database of each user's most recent login.
  132. .SH KEYWORDS
  133. user log, user ID, sprite ID
  134. .SH SEE ALSO
  135. db, mig, Mig_GetInfo, login, rlogin, rlogind
  136.